home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
IRIX Base Documentation 1998 November
/
IRIX 6.5.2 Base Documentation November 1998.img
/
usr
/
share
/
catman
/
p_man
/
cat3
/
libstiff.z
/
libstiff
Wrap
Text File
|
1998-10-30
|
21KB
|
550 lines
LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333)))) IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333))))
LLLLIIIIBBBBRRRRAAAARRRRYYYY DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
_l_i_b_s_t_i_f_f provides a C Language application programming interface (API)
for the reading and writing of Stream TIFF files. Stream TIFF (STIFF) is
a subset of the Tag Image File Format (TIFF) originally developed by
Aldus Corporation. The TIFF file format is an extremely flexible format
well suited for monochrome and color bitmap images. The difference
between TIFF and STIFF is that while a TIFF file may require file seeking
during reading or writing a STIFF file does not. This means that a STIFF
file can be read from and written to non-seekable streams such as pipes
and sockets. It is important to note that a STIFF file may be read by any
TIFF reader that conforms to the TIFF Revision 6.0 specification.
However, the _l_i_b_s_t_i_f_f API should not be used to read standard TIFF files.
The functions provided by _l_i_b_s_t_i_f_f greatly simplify the reading and
writing of TIFF compatible files. Using the STIFF API, TIFF compatible
files can be read and written without the need to understand the
structure of a TIFF file and without the need to explicitly specify TIFF
tags.
LLLLIIIIBBBBRRRRAAAARRRRYYYY AAAACCCCCCCCEEEESSSSSSSS
There are two sets of _l_i_b_s_t_i_f_f functions. One set comprises the generic
_l_i_b_s_t_i_f_f API. These functions are designated by an SSSSTTTT prefix. These
functions may be used to read and write generic STIFF files. To access
these functions an application must include the header file _s_t_i_f_f._h
located in the /_u_s_r/_i_n_c_l_u_d_e directory. The second set of _l_i_b_s_t_i_f_f
functions are a subset of the generic functions and are tailored to
reading and writing STIFF files that are to be passed between printing
filters and drivers. These printing related functions are designated by
the prefix PPPPSSSSTTTT and are accessed through the header file _p_r_i_n_t_s_t_i_f_f._h also
located in /_u_s_r/_i_n_c_l_u_d_e. If _p_r_i_n_t_s_t_i_f_f._h is used, the header _s_t_i_f_f._h
need not be specified. The generic and printing specific functions may
be freely intermixed within an application. All _l_i_b_s_t_i_f_f functions
require that the _s_t_d_i_o._h file be included.
Programs that call _l_i_b_s_t_i_f_f functions must link with the _l_i_b_s_t_i_f_f._a
library located in the directory /_u_s_r/_l_i_b.
FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNNSSSS
GGGGeeeennnneeeerrrriiiicccc FFFFuuuunnnnccccttttiiiioooonnnnssss
SSSSttttrrrreeeeaaaammmm HHHHaaaannnnddddlllliiiinnnngggg
STOpen
STClose
STSkipTo
RRRReeeeaaaaddddiiiinnnngggg aaaannnndddd WWWWrrrriiiittttiiiinnnngggg
STReadImageHeader
STWriteImageHeader
STRead
STWrite
PPPPaaaaggggeeee 1111
LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333)))) IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333))))
TTTTIIIIFFFFFFFF TTTTaaaagggg SSSSuuuuppppppppoooorrrrtttt
STAddTag
STRemoveTag
STGetTag
STPrintTags
EEEExxxxeeeeccccuuuuttttiiiioooonnnn EEEErrrrrrrroooorrrr HHHHaaaannnnddddlllliiiinnnngggg
STPerror
STErrorString
PPPPrrrriiiinnnnttttiiiinnnngggg SSSSppppeeeecccciiiiffffiiiicccc FFFFuuuunnnnccccttttiiiioooonnnnssss
RRRReeeeaaaaddddiiiinnnngggg aaaannnndddd WWWWrrrriiiittttiiiinnnngggg
PSTReadImageHeader
PSTWriteImageHeader
UUUUSSSSIIIINNNNGGGG TTTTHHHHEEEE LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNNSSSS
WWWWrrrriiiittttiiiinnnngggg AAAA SSSSTTTTIIIIFFFFFFFF FFFFiiiilllleeee
The typical sequence of operations for writing a STIFF file is as
follows:
1. Obtain a writable file descriptor. Note that this descriptor can be
associated with a non-seekable stream.
2. Call _S_T_O_p_e_n with the writable file descriptor and the flag SSSSTTTT____WWWWRRRRIIIITTTTEEEE.
3. Fill in the STIFF image header (_S_T_I_m_a_g_e_H_e_a_d_e_r or _P_S_T_I_m_a_g_e_H_e_a_d_e_r).
4. Optionally, add any application specific TIFF tags to the file using
_S_T_A_d_d_T_a_g.
5. Call the image header write function _S_T_W_r_i_t_e_I_m_a_g_e_H_e_a_d_e_r.
6. Write the image data using _S_T_W_r_i_t_e.
7. Repeat steps 3 through 6 for each page of image data.
8. Close the STIFF stream using _S_T_C_l_o_s_e.
9. Close the file descriptor.
RRRReeeeaaaaddddiiiinnnngggg AAAA SSSSTTTTIIIIFFFFFFFF FFFFiiiilllleeee
The typical sequence of operations for reading a STIFF file is as
follows:
1. Obtain a readable file descriptor. Note that this descriptor can be
associated with a non-seekable stream.
2. Call _S_T_O_p_e_n with the readable file descriptor and the flag SSSSTTTT____RRRREEEEAAAADDDD.
3. Call the image header read function _S_T_R_e_a_d_I_m_a_g_e_H_e_a_d_e_r or
_P_S_T_R_e_a_d_I_m_a_g_e_H_e_a_d_e_r.
PPPPaaaaggggeeee 2222
LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333)))) IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333))))
4. Access the fields of the image header structure to determine the
amount of image data to be read for this page.
5. Optionally, obtain the values for any application specific TIFF tags
from the file using _S_T_G_e_t_T_a_g.
6. Read the image data using _S_T_R_e_a_d.
7. Repeat steps 3 through 6 for each page of image data. The last page
of image data will either have its _l_a_s_t image header field set to
one or will be an empty page (i.e. amount of data equals zero).
8. Close the STIFF stream using _S_T_C_l_o_s_e.
9. Close the file descriptor.
If an error condition is returned by a _l_i_b_s_t_i_f_f function, _S_T_P_e_r_r_o_r can be
used to print a diagnostic error message to the standard error.
GGGGEEEENNNNEEEERRRRIIIICCCC SSSSTTTTIIIIFFFFFFFF FFFFIIIILLLLEEEE SSSSTTTTRRRRUUUUCCCCTTTTUUUURRRREEEE
While it is not necessary to understand the STIFF file structure to use
_l_i_b_s_t_i_f_f, this explanation is provided for those who need to know. A
Stream TIFF file is first and foremost a valid TIFF file. STIFF is
derived from the TIFF 6.0 Specification available from Aldus Corporation
(see below). The terms used below to describe a STIFF file (e.g. IFD) are
explained in the TIFF specification and will not be described here.
The primary restriction STIFF places on the TIFF structure is that all
data must be read from or written to the file without the need to seek
within the file. Specifically, within a STIFF file:
1. The bitmap image data must be in page number order.
2. Data which does not fit in the value section of a tag must be
located immediately after the IFD and must occur in the same order
in which the tags are encountered. The exception to this is the
image data itself, which must come last for each page.
3. Image data must immediately follow the IFD and any offset values
associated with it.
4. A terminating, empty IFD will always be added to the end of the
STIFF file. This IFD guarantees that an IFD with 0000 in its 'next
IFD' field will appear in the IFD chain. Note that this empty IFD
will not be encountered when following IFD pointers if the last
'real' IFD is written with the 'last' parameter set to 1. While the
TIFF specification states that IFDs should not be empty, relaxing
this restriction appears to have no impact on TIFF compatibility.
PPPPaaaaggggeeee 3333
LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333)))) IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333))))
A STIFF file can be represented diagrammatically as:
_______________________________
TIFF header (8 bytes)
_______________________________
Optional intervening space
_______________________________
IFD for page 1
_______________________________
Data for long values in IFD 1
_______________________________
Image data for page 1
_______________________________
Optional intervening space
_______________________________
IFD for page 2
_______________________________
Data for long values in IFD 2
_______________________________
Image data for page 2
_______________________________
...
_______________________________
Terminating empty IFD
_______________________________
||||||||||||||||||||||||||||||||||||||||||||
||||||||||||||||||||||||||||||||||||||||||||
The _l_i_b_s_t_i_f_f functions support only the Motorola (MM) byte ordering. In
addition to supporting TIFF class B, G and R data, _l_i_b_s_t_i_f_f supports the
CMYK color image data type (PhotoMetricInterpretation = 5 and InkSet = 1)
and four additional color image separation types: CMY, YMC, YMCK, and
PPPPaaaaggggeeee 4444
LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333)))) IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333))))
KCMY. For these additional types, PhotoMetricInterpretation = 5, InkSet
= 2, NumberOfInks = 3 or 4, and the InkNames tag is used to indicate the
inks contained in each channel.
When reading an image header, _l_i_b_s_t_i_f_f parses the ink names for these
additional types, and sets the _t_y_p_e field of the SSSSTTTTIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr structure
to the appropriate value defined in <_s_t_i_f_f._h>. When writing an image
header, _l_i_b_s_t_i_f_f writes the appropriate PhotoMetricInterpretation,
InkSet, NumberOfInks, and InkNames tags based on the value of the _t_y_p_e
field of the SSSSTTTTIIIImmmmaaaaggggeeeeHHHHeeeeaaaaddddeeeerrrr structure.
PPPPaaaaggggeeee 5555
LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333)))) IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333))))
The CMYK data class is a TIFF data format extension.
TTTTaaaagggg PPPPoooossssssssiiiibbbblllleeee VVVVaaaalllluuuueeeessss
_________________________________________________________
BitsPerSample (1,1,1,1) (4,4,4,4) (8,8,8,8)
PhotoMetricInterpretation 5
SamplesPerPixel 4
PlanarConfiguration 1,2
NumberOfInks 4
The CMY data class is a subset of the CMYK class and differs from the
CMYK class in a TIFF compliant manner. In the description of the
SamplesPerPixel tag below, "1 bit planar" refers to the case where
BitsPerSample has the value (1,1,1,1) and PlanarConfiguration has the
value 2.
TTTTaaaagggg PPPPoooossssssssiiiibbbblllleeee VVVVaaaalllluuuueeeessss
_____________________________________________________________
BitsPerSample (1,1,1,1) (1,1,1) (4,4,4) (8,8,8)
PhotoMetricInterpretation 5
SamplesPerPixel 3 (4 for 1 bit planar)
PlanarConfiguration 1,2
NumberOfInks 3
The YMC data class is a class similar to the CMY class with the exception
that data is organized as YMC instead of CMY. When using _l_i_b_s_t_i_f_f, YMC
data corresponds to the data type SSSSTTTT____TTTTYYYYPPPPEEEE____YYYYMMMMCCCC.
TTTTaaaagggg PPPPoooossssssssiiiibbbblllleeee VVVVaaaalllluuuueeeessss
_____________________________________________________________
BitsPerSample (1,1,1,1) (1,1,1) (4,4,4) (8,8,8)
PhotoMetricInterpretation 5
SamplesPerPixel 3 (4 for 1 bit planar)
PlanarConfiguration 1,2
NumberOfInks 3
InkSet 2
InkNames yellow,magenta,cyan
The YMCK class is a class similar to the CMYK class with the exception
that data is organized as YMCK instead of CMYK. When using _l_i_b_s_t_i_f_f,
YMCK data corresponds to the data type SSSSTTTT____TTTTYYYYPPPPEEEE____YYYYMMMMCCCCKKKK.
TTTTaaaagggg PPPPoooossssssssiiiibbbblllleeee VVVVaaaalllluuuueeeessss
_________________________________________________________
BitsPerSample (1,1,1,1) (4,4,4,4) (8,8,8,8)
PhotoMetricInterpretation 5
SamplesPerPixel 4
PlanarConfiguration 1,2
NumberOfInks 4
InkSet 2
PPPPaaaaggggeeee 6666
LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333)))) IIIImmmmpppprrrreeeessssssssaaaarrrriiiioooo LLLLIIIIBBBBSSSSTTTTIIIIFFFFFFFF((((3333))))
InkNames yellow,magenta,cyan,black
The KCMY class is a class similar to the CMYK class with the exception
that the data is organized as KCMY instead of CMYK. When using _l_i_b_s_t_i_f_f,
KCMY data corresponds to the data type SSSSTTTT____TTTTYYYYPPPPEEEE____KKKKCCCCMMMMYYYY.
TTTTaaaagggg PPPPoooossssssssiiiibbbblllleeee VVVVaaaalllluuuueeeessss
_________________________________________________________
BitsPerSample (1,1,1,1) (4,4,4,4) (8,8,8,8)
PhotoMetricInterpretation 5
SamplesPerPixel 4
PlanarConfiguration 1,2
NumberOfInks 4
InkSet 2
InkNames black,cyan,magenta,yellow
Note that for the RGB, CMY, and YMC classes with BitsPerSample values of
(1,1,1) and a PlanarConfiguration value of 1, pixels are stored two to a
byte, with the bits ordered from most to least significant. For example,
CMY data is stored as: CMY0CMY0. Rows are padded to contain an integral
number of bytes.
Refer to the header file _s_t_i_f_f._h for additional information regarding the
STIFF file structure.
PPPPRRRRIIIINNNNTTTTIIIINNNNGGGG SSSSPPPPEEEECCCCIIIIFFFFIIIICCCC SSSSTTTTIIIIFFFFFFFF
The printing specific functions (PST) provided by _l_i_b_s_t_i_f_f to read and
write STIFF files as described above. The printing specific aspect of
these functions is found in the image header structure. The printing
specific image header (PSTImageHeader) contains all fields of the
(STImageHeader) plus printing specific information fields such as image
resolution and halftoning method. If a STIFF stream is written using the
generic functions and is read using the printing specific functions,
default values will be used for the PSTImageHeader fields not found in
the STIFF stream. Similarly, a STIFF stream written using the printing
specific functions can be read by the generic functions. In this case,
the additional information in the stream can be ignored or obtained using
the _S_T_G_e_t_T_a_g function.
Refer to the header file _p_r_i_n_t_s_t_i_f_f._h for additional information
regarding printing specific STIFF.
SSSSEEEEEEEE AAAALLLLSSSSOOOO
_v_s_t_i_f_f(1), _z_o_o_m_s_t_i_f_f(1).
_T_I_F_F _6._0 _S_p_e_c_i_f_i_c_a_t_i_o_n - Aldus Corporation, 1992. For a copy of the TIFF
6.0 specification contact Aldus Developers Desk, Aldus Corporation, 411
First Avenue South, Seattle, WA 98104-2871, (206) 628-6593.
PPPPaaaaggggeeee 7777